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ABSTRACT 

The  WATCHR  III  system  for  the  66OO  provides  traces  of 
selected  Instructions  (Including  all  Instructions),  traces 
of  changes  to  selected  variables,  traces  of  the  path  taken 
by  the  user's  program,  traces  of  changes  to  selected 
registers,  traces  of  selected  loads,  traces  of  selected 
subroutine  calls.   It  provides  traps  on  selected  addresses, 
selected  locations  stored  into,  selected  address  loaded  from, 
and  selected  op  codes.   It  provides  the  capability  of  dumping 
part  of  core  at  any  time  and  anywhere  within  the  field  length, 
the  dump  being  either  in  octal,  integer,  floating  point,  or 
alphanumeric,  with  excessive  duplications  suppressed.   It 
provides  a  dump  of  the  user's  registers  at  any  time.   It 
provides  error  checking  facilities  for  out-of-bounds  jumps, 
memory  references,  arith  errors,  etc.,  indefinite  and  infinite 
results,  wild  stores  and  loads,  infinite  loops  (heuristic), 
incorrect  values  for  selected  variables.   (If  an  error  is 
found,  a  trace  of  the  6OO  instructions  leading  up  to  the 
error  is  given  automatically.)   It  also  provides  to  the  user 
the  aballity  to  examine  core  or  his  registers  during  the  run 
and  provides  recovery  in  case  of  fatal  errors. 

The  program  operates  on  any  Central  Processor  binary 
code,  simulates  the  action  of  the  CPU,  and  gathers  information 
as  directed  by  switch  settings.   Switches  may  be  set  or  unset, 
selections  made  or  unmade  at  any  time;  and  the  user's  program 
may  go  under  WATCHR ' s  control  or  out  of  it  at  any  time  at  the 
option  of  the  user. 
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WATCHR  III 
A  Program  Analyzing  and  Debugging  System 
for  the  CDC  66OO 
USER'S  MANUAL 

Introduction . 

Purpose.   The  purpose  of  WATCHR  Is  to  save  programmer 

and  machine  time  and  to  reduce  the  time  between 

the  beginning  and  the  completion  of  a  project. 

Obviously,  If  this  system  Is  used  as  a  last  resort, 

none  of  these  objectives  can  be  accomplished. 

The  routine  may  also  be  used  to  gather  Information 

about  an  unfamiliar  program. 

It  may  also  be  used  to  study  the  functioning  of 

a  program  during  actual  execution.   The  routine 

is  so  generalized  and  open-ended  that  no 

exhaustive  list  of  its  applications  or  of  techniques 

for  its  use  can  be  given. 

Memory  Requirements .   The  WATCHR  package  occupies  25g  k 

central  memory  words.   (To  compile  under  RUN,  a 
minimum  field  length  of  7OOOOB  is  usually  required . ) 

Usage .    The  binary  cards  may  be  Included  as  a  normal 

subroutine,  or  the  subprograms  comprising  WATCHR 

may  be  called  from  the  system  tape. 

To  trace  the  compiler,  the  assembler,  WATCHR,  or 
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other  systems,  other  steps  must  be  taken. 
(See  Appendix  C . ) 

I.   Initialization . 

1.  Initialization  call.   Before  any  use  can  be  made  of  any 
WATCHR  facility,  the  following  call  must  be  executed. 
It  need  be  executed  only  once. 

(Fortran)  (Ascent) 

CALL  WATCHR  RJ   WATCHR 

(Of  course.  In  Ascent  all  references  to  WATCHR  options 
must  be  declared  external.) 

2.  Entry.   WATCHR  may  be  entered  and  exited  from  as  often 
as  desired;  however,  the  entry  call  must  not  be  repeated 
until  an  exit  call  has  been  executed.   Switches  set  by 
an  entry  call  will  remain  until  explicitly  changed  by 

a  succeeding  entry  call;  therefore,  switches,  once  so 
set  need  not  be  re-set  on  succeeding  entries. 

SBl    BA 
CALL  WATCHIT(KBA)         RJ    WATCHIT 

BA  or  KBA  Is  the  base  address  of  the  parameter  list. 

If  BA  contains  a  zero.  It  will  be  assumed  that  the 

rest  of  the  parameters  are  zero;  but  If  the  first 

parameter  is  given,  the  rest  must  be  given,  whether 

zero  or  not . 


KBA(1)=T0PADDR  BA   CON  TOPADDR 

KBA ( 2 ) =LLBA  CON  LLBA 

KBA ( 3 ) =REGADDR  CON  REGADDR 

KBA (4)=  SUBLIST  CON  SUBLIST 

KBA(5)=C0NS0LE  CON  CONSOLE 

KBA(6)=SHARER  CON  SHARER 

KBA(7)=EXITM0DE  CON  EXITMODE 

("TOPADDR",  "LLBA",  etc.  are  merely  Idlophonlc 
sign- types,  not  sign-tokens,  and  must  be  replaced 
in  practice  by  any  appropriate  constant  or  variable.) 
"TOPADDR"  represents  a  number  which  Is  the  top-most 
address  which  the  user  wishes  to  allow  his  program  to 
reference:   It  should  be  shorter  than  the  field  length. 
"LLBA"  represents  (if  non-zero)  the  base  address  of  a 
list  of  line  limits  which  the  user  may  set.   Any  may  be 
zero  in  which  case  WATCHR's  limits  will  be  used. 
The  options  are: 

1.  LIMIT  (for  OPTRACE  and  REPORT)       (^OOO^q  lines) 

2.  LOCLIMIT  (for  LOCTRACE)  (3000^^  lines) 
5.  REGLIMIT  (for  REGIRACE)  (3000^^  lines) 
h.    MAPLIMIT  (for  MAP)                   (8000^^  lines) 
5.  DUMPLIM  (for  DUMP)                   (5000^^  lines) 
These  numbers  do  not  include  the  user's  program's 
normal  output,  and  no  checks  of  any  sort  are  provided 
for  such  output.  (If  one  line  limit  is  explicitly  stated, 
all  must  be . ) 
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"REGADDR",  if  non-zero.  Is  an  address  of  a  26-word 

buffer  at  which  a  copy  of  the  user's  program's 

registers  will  be  stored  in  the  event  of  a  trap. 

The  registers  will  be  in  order  A,B,X  with  each  register 

in  a  separate  word  (followed  by  the  P  register  and  the 

current  instruction  word).   Any  changes  made  to  these 

locations  during  a  "trap  routine"  will  exist  in  the 

user's  registers  when  his  normal  program  resumes. 

(I  call  "trap  routine"  only  any  set  of  instructions 

which  the  user  wishes  to  execute  in  the  event  of  a 

"trap",  or  i.e.  "breakpoint",  or  i.e.  "interrupt".) 

"SUBLIST",  if  non-zero,  is  the  base  address  of  a  list 

of  addresses,  each  of  which  is  the  address  of  a  subroutine 

which  the  user  wishes  executed  outside  of  WATCHR  control. 

These  subroutines  may  be  system  subroutines,  library 

routines,  or  the  user's  own  subroutines  concerning  which 

he  wishes  to  make  no  use  of  WATCHR. 

"CONSOLE",  if  non-zero,  will  enable  the  user  to  run  in 

console  mode,  for  use  of  the  display  console.   (See 

Appendix  C . ) 

"SHARER",  if  non-zero,  will  enable  to  user  to  use 

WATCHR  on-line  at  a  teletype  console  under  the  SHARER 

system.   The  program  may  not  be  in  both  console  mode 

and  SHARER  mode  at  the  same  time,  and  SHARER  mode  has 

precedence. 
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"EXITMODE",  if  non-zero,  gives  the  arithmetic  exit 
mode  in  which  the  use  wishes  to  run.  The  modes, 
0  through  7,  are  the  same  as  the  operating  system 
modes  with  two  exceptions:   1.  No  mode  0  is  provided, 
and  2.  In  mode  1,  out  of  bounds  memory  references 
will  not  be  performed,  but  the  program  will  not  halt. 
If  this  option  is  omitted,  mode  7  will  be  assumed. 

Example  1: 

CALL   ¥ATCHIT(0)  SBl     BO 

RJ      WATCHIT 

Example  2: 

INTEGER  XLOCP 
DIMENSION  KBA(7) 
KBA(l)  =  5OOOOB 
KBA(2)  =  XLOCP (LLBA) 
KBA(3)  =  XLOCP (KADDR) 
KBA(4)  -  XLOCP (KSUBADD) 
KBA(5)  =  1 
KBA(6)  =  0 
KBA(7)  =  3 
CALL  WATCHIT (KBA) 
(Note:  Any  WATCHR  options  may  be  set  or  unset  at  any  time, 

whether  or  not  the  user's  program  is  then  running  under 

WATCHR  control.   However,  the  options  will  not  function 

except  when  the  program  is  running  under  WATCHR.   This 

is  true  even  during  trap  routines.   The  only  exceptions 

are  WDUMP  and  COMPARE,  which  may  be  utilized  at  any  time, 

and  REP0RT(4)  and  SNAP,  which  may  only  be  called  under 

WATCHR . ) 


(Note;  WATCHR's  procedure  in  case  of  erroneous  calls  to  its 
various  options  is  generally  to  omit  the  erroneous 
parameter  if  possible,  or  to  omit  that  call  to  the 
option.   In  certain  cases  it  withdraws  an  option 
completely  for  the  duration  of  a  run.   But  it  never 
terminates  a  run  on  account  of  an  erroneous  call.) 
3.  Exit .  Exit  from  WATCHR  returns  program  control  to  the 
user's  program. 

CALL  DON¥ACH(N) 
"N"  represents  a  constant  which  may  be  either  zero  or 
non-zero.   If  zero,  all  switch  settings  will  remain 
as  they  are;  if  non-zero,  all  switch  settings  (other 
than  those  set  by  the  entry  call)  will  be  turned  off. 

II.   Error  Checking. 

A.   Unrequested  Checks.   The  following  validity  checks  are 
not  optional  and  are  always  performed  when  the  user's 
program  is  running  under  WATCHR . 

1.  Generation  of  infinite  and  Indefinite  results.  Up  to 
50  messages  are  given.   Thereafter,  these  results  will 
not  be  flagged  when  they  are  produced. 

2.  Out  of  bounds  jumps .   A  branch  to  some  address  greater 
than  that  given  as  the  upper  limit  or  an  illegal  jump 
into  the  area  occupied  by  WATCHR  will  result  in  a 
termination  at  the  fatal  error  exit. 
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5-   Execution  of  data.   When  a  ^O-blt  op  code  is  found 
in  the  right-most  quarter  of  a  word,  it  is  assumed 
that  the  program  is  trying  to  execute  data  and  fatal 
termination  results. 

h.  Next  instruction  out  of  bounds.  If  the  address  of  the 
next  instruction  in  sequence  is  greater  than  the  upper 
limit  or  is  within  WATCHR,  a  fatal  '^rror  is  assiimed. 

5.  Arith  errors .   Attempts  to  use  an  indefinite  or 
infinite  operand  are  flagged  and,  depending  on  the  exit 
mode  selected,  may  lead  to  fatal  termination.   No  limit 
on  these  printouts  is  provided. 

6.  PP  call  errors ■   A  check  is  made  to  insure  that  stores 
into  location  1  contain  legal  display  code.   Stores 
into  location  0  are  also  checked  to  some  extent.   Both 
may  lead  to  fatal  termination. 

7-    Stop  code.   If  a  program  stop  is  encountered,  fatal 

termination  will  result.   A  program  is   assumed  to  end 
with  a  call  to  EXIT  or  with  END. 

B.    Fatal  Error  Exit.   At  this  exit  a  snapshot  of  the 

registers  is  produced  and  a  full  trace  of  the  up-to 
600  most  recent  instructions  (those  which  led  to  this 
fatal  error) .   Also,  a  full  report  is  produced  (see 
REPORT) .   Then,  if  the  RECOVR  option  is  not  on,  an 
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octal  dump  of  the  100  locations  surrounding  the  address 
of  the  error  is  given.  Otherwise,  the  program  recovers 
and  continues  processing. 

C.   Optional  Validity  Checks. 
1.  Answers .   A  check  on  the  values  assumed  by  various 

variables,  or.  I.e.  on  the  numbers  stored  Into  selected 
locations.  Is  provided.   The  check  may  apply  to  values 
obtained  anywhere  In  the  program  or  It  may  be  restricted 
to  values  obtained  only  at  a  single  address.   In  each 
case,  all  correct  answers  or  as  many  incorrect  answers 
as  desired  must  be  given.   A  single  relation  (of  "equal 
to",  "greater  than",  or  "less  than")  which  the  current 
value  bears  to  each  value  on  the  list  must  be  selected 
for  each  variable.   The  same  variable  may  be  selected 
more  than  once. 

(Note:   parameter  list  resides  (in  this  case)  permanently 
in  the  user's  program  area.   The  parameters  may,  thus, 
be  modified  at  will  without  a  new  call  to  CHECKR . ) 
An  exit  procedure  must  be  selected  for  each  variable: 
the  user  may  continue  processing  (having  obtained  an 
error  printout  on  his  output,  he  may  trap  to  a  trap 
routine  which  he  provides  for  more  extended  and  specific 
diagnosis,  or  he  may  go  to  the  fatal  error  exit  where 
a  backup  trace  will  be  given  and  where  a  recovery  may 
be  made. 
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KBA(2)  =  ADD 


(Note:   an  answer  of  zero  cannot  be  checked,  and  not  more 
than  2000^ „  parameters  may  be  given  to  CHECKR  at  any 
one  time,  else  the  check  will  be  turned  off  permanently.) 

CALL  CHECKR (KBA) 
The  parameter  list  is  as  follows: 
KBA(l)  =  LOC       (the  variable,  or  a  zero  if  CHECKR 

is  being  turned  off) 
(the  address  at  which  the  variable 
is  changed,  or  zero  if  any  (every) 
address  is  desired) 

(the  relation:   a  -1  for  "less  than"; 
zero  for  "equals";  4-1  for  "greater  than") 
KBA (4)  =  TERMPROC   (termination  procedure  in  case  a  wrong 

answer  is  found;  zero  for  "continue"; 
1  for  "fatal  exit";  any  other  number 
will  be  assumed  to  be  a  trap  address) 
KBA(5)  =  TYPE      (indicates,  if  +1,  that  the  answers 

which  follow  are  correct;  -1,  incorrect) 
KBA(6)  =  ANSI      (the  answers) 


KBA (5)=   R 


KBA(  )  =  ANSn 
KBA(  )  =  0 
KBA(  )  =  SEP 


(end  of  answer  list) 

(a  positive  number  is  taken  to  be  a 
new  LOC,  a  zero  signals  the  end  of 
the  entire  parameter  list) 
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Thus,  a  double  zero  Is  required  to  terminate  the  list. 

The  above  sequence  may  be  repeated  for  as  many  LOG ' s 

as  are  desired.   A  call  to  turn  off  CHECKR  does  not 

destroy  the  parameter  list,  thus  alternative  lists 

may  be  used . 

Example: 

KBA(l)  =  XLOCF(ZPRIME) 

KBA(2)  =  0 

KBA(3)  =  0 

KBA(4)  =  0 

KBA(5)  =  1 

KBA(6)  =  2154OOOOOOOOOOOOOOOOB 

KBA(7)  =  2I54OOOOOOOOOOOOOOOOB 

KBA(8)  =  21640OOOOOI263522407B 

KBA(9)  =  0 

KBA(10)=  XLOCP(J) 

KBA(11)=  0 

KBA(12)=  0 

KBA(13)=  1 

KBA(l4)=  -1 

KBA(15)=  56 

KBA(l6)  =0 

KBA(17)  =0 

CALL  CHECKR (KBA) 

(In  this  example,  the  subscript  "J"  Is  being  checked 

to  insure  that  it  does  not  exceed  a  buffer  limit  for 

some  buffer  55  words  long;  and  ZPRIME  is  being  watched 

to  see  if  it  assumes  any  other  values  than  those  given.) 
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2 .  Recovery. 

To  insure  that  all  sections  and  subroutines  of  a  program 
receive  a  legitimate  test,  a  list  of  the  starting 
addresses  of  such  subroutines  or  sections  may  be  given, 
each  with  Its  list  of  "input"  (i.e.  the  contents  of 
any  registers  or  the  contents  of  any  addresses  which 
that  subroutine  assumes). 

On  each  recovery,  the  list  will  be  searched  for  a 
subroutine  which  has  not  yet  been  entered.   When  one 
Is  found.  Its  Input  will  be  set  up.  It  will  be  marked 
"processed"  and  execution  will  be  resumed,  a  printout 
marking  the  spot  in  the  output.   If  it  is  desired  to 
process  a  given  subroutine  more  than  once,  the  first 
word  of  the  subroutine  (the  entrance)  must  be  cleared 
and  the  subroutine  and  its  input  must  appear  more  than 
once  in  the  parameter  list. 

The  parameter  list  resides  in  the  user's  program  area 
and  should  not  be  changed.   A  call  to  turn  off  this 
option  does  not  damage  the  list,  and  RECOVR  may  be 
called  again  with  a  different  list  without  ever  having 
been  turned  off.   However,  only  one  parameter  list  is 
in  effect  at   any  one  time. 

CALL  RECOVR  (KBA) 
The  parameter  list  is  as  follows: 
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KBA(l)  =  LOG 


KBA(2) 
KBA(3) 


REGl 
CONTENTS 


(The  address  of  the  first  word  of  a 
subroutine  or  section  of  coding,  or 
a  zero  if  RECOVR  is  being  turned  off) 
(the  coded  number  of  a  register  or 

an  address  in  memory) 
(the       contents  of  the  register 

or  of  the  address) 


KBA(  )  =  ADDl       (an  address  and  its       contents. 
KBA(  )  =  CONTENTS    If  registers  are  given,  they  must 

be  given  before  any  memory  address) 
(repeated  for  as  many  registers  or 

addresses  as  desired) 
KBA(  )  =  0  (end  of  this  subroutine's  input) 

KBA(  )  =  K  (the  LOG  of  another  subroutine  or 

zero  to  mark  the  end  of  the  parameter 

list) 

(Thus,  a  double  zero  is  required  to  terminate  the  list. 
No  input  need  be  specified,  so  that  the  third  parameter 
might  be  the  address  of  another  subroutine. 
Restriction:   Register  AO  may  not  be  included  in  the 
parameter  list.) 

(Registers  are  coded  in  the  following  way:   a  two-digit 
octal  number,  of  which  the  first  digit  specifies  the  A 
register  (if  0),  the  B  register  (if  1),  or  the  X 
register  (if  2) .   The  second  digit  specifies  the 
register  number.   Thus,  e.g.  Olg  is  Al,  25g  is  X5,  etc.) 
An  alternative  parameter  list  is  also  provided.   In 
this  case,  control  is  returned  to  the  user  at  the  address 
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specified.   At  this  address  the  user  may  set  up  his 

own  input  or  make  his  own  diagnosis.  He  may  utilize 

WATCHR  again  by  calling  WATCHIT  in  the  usual  way. 
KBA(l)  =  -1 
KBA(2)  =  TRAPADDl 
KBA(3)  =  -1 
KBA(4)  =  TRAPADD2 

KBA(  )  =  0 
KBA(  )  -  0 

Each  time  a  fatal  error  occurs,  the  next  TRAP ADD  in  the 

list  will  be  taken.   The  same  TRAP ADD  may  appear  on  the 

list  more  than  once.   A  new  list  may  be  established  at 

any  time  by  a  call  to  RECOA/R . 

Example: 

INTEGER  XLOCP 

KBA(l)  =  XLOCF(PRINTEM) 

KBA(2)  =  IIB 

KBA(3)  =  XLOCF(PARAMS) 

KBA(4)  =  XLOCP (SWITCH) 

KBA(5)  =  7O7O7O7O7O7O7O7O7O7OB 

KBA(6)  =  0 

KBA(7)  =  0 

CALL  RECOVR(KBA) 

(In  this  example,  the  subroutine  "PRINTEM"  is  to  be 

executed  in  case  of  a  fatal  error  to  print  out  answers 

or  whatever.   (This  subroutine  must  call  EXIT  or  take 

care  of  its  own  continuation  procedures  itself.)   Bl  is 

set  to  the  address  of  some  parameters  used  by  the 

subroutine  "PRINTEM",  and  a  switch  is  set.) 
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3-  Compare .   At  any  point  In  a  routine,  the  user  may 

check  the  contents  of  any  registers  or  memory  locations 
for  certain  required  values.   If  discrepancies  are 
found,  they  will  be  corrected,  messages  will  specify 
the  corrections  and  where  they  were  made,   and 
processing  will  continue.   Each  call  to  COMPARE  will 
perform  a  single  on-the-spot  check  (the  check  is  not 
continuous  from  that  point  forward).   The  parameters 
reside  in  the  user's  program  and  may  be  changed 
whenever  desired  or  preserved  for  future  checks. 

CALL  COMPARE  (KBA) 
The  parameter  list  is  as  follows: 

KBA(l)  =  REGl       (the  first  register  or  the  first 

address.   If  AO  is  selected,  it 
must  come  first;  otherwise,  order 
is  immaterial) 
KBA (2)  =  CONTENTS    (the  contents  of  the  register  or  address) 

•  •  • 

KBA(  )  =  ADDl 

KBA(  )  =  CONTENTS    (up  to  3000^^  addresses  and 

registers  may  be  checked) 
KBA(  )  =  0  (terminates  the  list) 

(The  code  numbers  for  the  registers  are  the  same  as 
for  RECOA/R . ) 
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h.    Check  for  erroneous  stores .   To  prevent  a  program  from 
wiping  out  Itself  or  to  locate  Incorrect  stores,  the 
storage  regions  of  a  program  may  be  gathered  together 
Into  several  areas  and  the  upper  and  lower  addresses 
of  these  areas  given  to  STORCHK  as  parameters.   In 
addition,  single  locations  may  be  given,  and  also  a 
"tolerance  limit".   The  tolerance  limit  will  make  It 
possible  for  addresses  not  on  the  list  to  be  stored 
Into  (though  they  will  be  flagged  each  time  ) . 
These  addresses  will  be  added  to  the  list.   When  the 
tolerance  limit  Is  exceeded,  attempted  stores  will  not 
be  made  but  will  be  printed  out  Instead  with  appropriate 
Information.   The  program  does  not  stop. 
CALL  STORCHK (KBA) 

The  parameter  list  Is  as  follows: 

KBA(l)  =  N         (This  constant  specifies  the  total 

number  of  parameters  on  the  list 
and  hence,  the  amount  of  space 
reserved  as  a  tolerance  limit  for 
additional  addresses) 
(If  zero,  the  check  is  turned  off) 

KBA(2)  =  LCWERl     (Lower  address  of  a  storage  region) 

KBA (3)  =  UPPBRl     (Upper  address  of  that  region) 


KBA(  )  =  LOWERn 

KBA(  )  =  UPPERn 

KBA(  )  =  0  (Separator) 

KBA(  )  =  ADDl       (A  legitimate  address  for  stores) 
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KBA(  )  =  ADDn 

KBA(  )  =  0         (Reserved  space,  if  any,  for  additional 

tolerated  storage  addresses) 

•  •  • 

KBA(  )  =  0 

(The  parameter  list  resides  in  the  user's  program  area 
so  that  he  can  determine  when  the  list  has  been  filled 
if  he  so  desires . ) 

5.  Check  for  erroneous  loads.   LOADCHK  is  analogous  to 
STORCHK  in  purpose  and  design,  so  that  the  same 
parameter  lists  can  be  used  for  both  if  desired. 
LOADCHK,  however,  has  no  tolerance  limit,  and  all 
loads  not  on  the  list  will  be  performed  and  flagged 
with  appropriate  messages . 

CALL  LOADCHK (KBA) 

The  parameter  list  is  as  follows: 
KBA(l)  =  LOWERl 
KBA (2)  =  UPPERl 

•  •  • 

KBA(  )  =  LOWERn 
KBA(  )  =  UPPERn 
KBA(  )  =  0         (Terminator  for  end  of  list) 

6.  Endless  loops.   This  is  a  heuristic  check  for  endless 
loops .   The  upper  limit  is  5000^q  times  through  the 
same  loop.   Only  programs  known  to  have  an  endless  loop 
should  use  LOOPCHK. 
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CALL  LOOPCHK(KBA) 

The  parameters  are  aa  follows: 

KBA(l)  =  RESPONSE   (This  constant  will  be  zero  at  the 

call  to  LOOPCHK  and  will  remain  zero 
until  WATCHR  has  satisfied  itself, 
then  KBA(l)  will  contain  a  1  if  no 
loop  can  be  found,  or  an  address  of 
the  Jump  instruction  which  seems 
always  to  be  jumping  in  the  same 
direction  and  thus  causing  the  loop) 

KBA(2)  =  TRADD     (If  given  as  non-zero,  this  will  be 

assumed  to  be  the  address  of  a  trap 
routine  provided  by  the  user,  and 
control  will  go  to  this  routine  if 
an  endless  loop  is  suspected,  other- 
wise, the  fatal  exit  will  be  taken) 

(To  regain  entrance  to  WATCHR  from  this  trap  routine, 

WATCHIT  must  be  called,  as  a  new  beginning.) 

Ill .    TRACES . 

A.   Instructions .   Instructions  may  be  selected  for  tracing 

by  means  of  their  op  codes.   Any  op  code  or  combination 

of  op  codes  in  any  order  may  be  selected.   If  op  code  00 

occurs  in  the  list,  all  instructions  will  be  traced, 

beginning  either  at  the  call  to  OPTRACE  or  at  the  time 

when  the  program  re-enters  WATCHR  control. 

CALL  OPTRACE (KBA) 

The  parameters  are  as  follows : 

KBA(l)  =  N     (The  number  of  op  codes  selected) 

KBA(2)  =   OPl    (An  op  code) 

KBA(  )  =  OPn 
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Exiting  from  WATCHR  control  will  discontinue  this  trace. 

After  the  call,  KBA(l),  KBA(2),  etc.  are  free  for  other 

uses;  changing  their  contents  will  not  alter  the  trace 

settings . 

Additional  settings  may  be  added  individually  or  in 

sets  by  additional  calls,  and  the  same  op  code  may  be 

selected  more  than  once  without  ill  effect. 

The  procedure  to  unset  these  traces  is  exactly  analogous 

and  the  interpretation  of  the  parameter  list  is  the  same. 

CALL   OPIROFF(KBA) 

Sample  of  the  output: 

1253  *   51100006715621056320  SAl  BO+671  B0=0   Al=671 

Xl=172170000000000 

(Thus,  the  address  of  the  instruction,  the  complete 
contents  of  that  address,  and  the  mnemonics  are  given, 
as  well  as  the  current  contents  of  registers  involved. 
The  last  coliomn  gives  the  results  of  the  instruction 
(in  this  case,  Al  became  67I  and  XI  became  I7217OOOOOOOO 
0000000.   These  numbers  are  all  octal .   For  floating  point 
instructions,  both  the  octal  and  the  floating  representa- 
tion is  printed.) 

Example:   SBl    BO  ,^  ..     .      ^        ^.  ^ 
RJ     OPTRACE        (Trace  all  instructions.) 

B.   Registers .   Any  combination  of  registers  in  any  order  may 
be  selected  for  tracing.   Thereafter,  whenever  a  selected 
registers  acquires  a  new  numerical  value,  the  contents 
of  that  register,  old.  and  new,  will  be  printed. 
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CALL  REGTRAC(KBA) 

The  parameter  list  is  as  follows: 

KBA(l)  =N      (The  number  of  registers  selected  at  this  call 

KBA(2)  =  SW    (If  1,  the  registers  which  follow  are  to 

be  added  to  the  list;  if  0,  they  are  to 
be  deleted  from  the  list;  if  otherwise, 
this  trace  is  to  be  turned  off  and  the 
settings  preserved) 

KBA(3)  =  REGl   (The  coded  number  of  a  register) 

KBA(n)  =  REGn 

The  parameter  list  is  free  after  the  call  for  other  uses. 
Sample  of  the  output: 

AT  P  =  274,  b6  which  was  000000  became  OO56OI. 
All  numbers  are  octal. 

Selecting  a  register  which  is  already  turned  on  will 
cause  an  error  printout  but  will  not  otherwise  affect 
the  program. 
(The  code  numbers  for  registers  are  two-digit  octal  numbers, 
of  which  the  first  digit  designates  the  A  register  (if  0), 
the  B  registers  (if  1),  or  the  X  registers  (if  2),  the 
second  digit  designates  the  particular  register. 
Thus,  e.g.  l6g  is  b6,  04g  is  A4,  and  27g  is  XJ. 
Numbers  larger  than  27o  will  be  flagged  as  errors  and 
disgarded,  but  will  not  otherwise  affect  the  program.) 
C.   Locations  changed.   Up  to  2000..  „  addresses  may  be 

selected  at  any  one  time  for  observation.   Thereafter, 
whenever  any  store  is  made  into  one  of  these  addresses. 
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it  and  Its  old  and  new  contents  will  be  printed  out. 

These  contents  will  be  printed  out  in  the  format 

specified  by  the  user,  and  the  same  address  may  be 

selected  more  than  once  with  a  different  format. 

The  parameter  list  resides  in  the  user's  program  area 

and  may  be  changed  whenever  desired  without  a  new  call 

to  LOCTRAC .   Each  call  presents  a  parameter  list  anew, 

so  that  alternative  lists  may  be  used  in  different  parts 

of  the  user's  program  for  the  sake  of  efficiency. 

Also,  provision  is  made  so  that  the  mnemonic  name  of 

the  variable  (i.e.,  the  location)  may  be  given. 

CALL  LOCTRAC (KBA) 

The  parameters  are  as  follows: 

KBA(l)  =  SW        (If  zero,  this  trace  is  suspended; 

if  1,  the  list  that  follows  is 

taken  as  the  parameter  list) 
KBA(2)  =  XLOCF(Z(3,256))   (An  address  or  variable  to 

be  watched) 
(If  the  parameter  is  "0"  all  stores 

will  be  printed  out) 
KBA(3)  =  lOH  Z(3,256)   (The  mnemonic  representation  of 

that  address  or  variable) 
KBA(4)  =  F         (The  format:  1  for  octal,  2  for  integer, 

3  for  floating  point,  h   for  BCD) 
(The  above  triple  may  be  repeated  as 

many  times  as  desired) 
KBA(n)  =  0         (Terminator) 
KBA(n+l)  =  0       (Terminator) 

If  the  terminating  zeros  are  omitted,  or  if  a  list  in 

excess  of  2000^ q  is  given,  this  option  will  be  withdrawn 
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for  the  duration  of  the  run  and  may  not  be  turned  on 
again  by  any  method  whatever.   Otherwise,  the  function- 
ing of  the  program  will  not  be  affected. 
(If  KBA(l)  becomes  -f   1  without  an  explicit  call  to 
LOCTRAC,  a  fatal  exit  is  taken.) 
Sample  of  the  output: 

AT  ADDRESS  00210?  ALT(45)   (OO5OO6)  WHICH  WAS  5  BECAME  6. 
(The  first  address,  OO2IO7,  is  the  address  at  which  the 
variable,  ALT(45)  ,  was  changed.   "ALT(4-5)  "  is  the  mnemonic 
which  was  set  up  on  the  parameter  list  by  the  user,  and 
its  address  is  OO5OO6  (octal).   In  this  example,  the 
trace  was  to  be  done  in  integer,  so  that  the  5  and  the  6 
may  be  decimal  numbers.) 
D.   The  path  taken  by  the  program.   To  discover  the  logical 
flow  or  sequence  of  instructions  for  a  given  run,  the 
MAP  option  may  be  turned  on.   At  periodic  intervals,  a 
printout  of  pairs  of  addresses  will  occur.   The 
starting  of  a  new  pair  signals  that  a  branch  occurred. 

CALL  MAP(N)   (If  N  is  zero,  the  option  is  turned  off, 
otherwise,  it  is  turned  on) 

Sample  of  the  output; 

MAP 

000244  -  000245   000233  -  000240    000232  -  000232 

000471  -  000472   000254  -  000256 

These  octal  addresses  show  that  the  program  went  from 

address  244  to  245  executing  instructions  in  sequence, 

then  a  branch  or  jump  occurred  to  233,  after  which  no 


25 


branch  occurred  until  address  240  which  jximped  to  232, 
etc . 
E.   Memory  references  (loads).   This  option  Is  analogous 
to  LOCTRAC  except  that  It  provides  for  a  long  comment 
giving  the  function  served  by  the  variable  being  loaded. 
The  purpose  of  this  option  is  to  make  it  apparent  to 
the  user  how  a  given  program  (under  observation)  actually 
works.   Not  more  than  2000, q  parameters  are  allowed. 

CALL  REFTRAG(KBA) 

The  parameter  list  is  as  follows: 

KBA(l)  =  SW        (If  zero,  the  trace  is  turned  off; 

if  1,  it  is  turned  on) 

KBA(2)  =  XLOCF(ADM) (An  address) 

KBA(3)  =  lOH  ADM   (The  mnemonic) 

KBA(4)  =  0         (Six  words  of  comments,  or  the  next 

address  on  the  list  (in  which  case 
group  (2)  and  (3)  would  be  repeated)) 

KBA(9)  =  0 

KBA(  )  =  0         (Terminator,  or  the  next  address  on 

the  list) 
KBA(  )  =  0         (Terminator) 

F.   Subroutine  calls.   This  option  is  analogous  to  REFTRAC 

except  that  return  jumps  are  traced.   Space  is  provided 

for  a  comment  detailing  the  purpose  of  each  subroutine. 

CALL  SUBTRAC(KBA) 

The  parameter  list  is  as  follows: 
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(Address  of  a  subroutine) 


(Comment) 

(Address  of  next  subroutine) 


KBA(l)  =  S¥ 
KBA(2)  =  XLOCP(EXP) 
KBA(3)  =  lOH  EXP 
KBA(4)  =  C 

KBA(9)  =  C 

KBA(IO)  =  XLOCP(SPS) 

KBA(ll)  =  lOH  SPS 

KBA(12)  =  lOH  SCHEDULE  (Comment) 

KBA(13)  =  lOH  PROGRAM  S 

KBA(14)  =  lOH  WAPS 

KBA(15)  =  lOH 

KBA(l6)  =  lOH 

KBA(17)  =  lOH 

KBA(  )   =  0 

KBA(  )  =   0 

Sample  of  the  output: 

005162  RJ  SPS   (011325)   SCHEDULE  PROGRAM  SWAPS 
The  first  octal  number  Is  the  address  of  the  call, 

and  the  second  is  the  address  of  the  subroutine. 

VI .   REPORTS 

A.   Snapshot  of  the  registers.   This  may  be  obtained  at  any 

time,  on  call. 


(Comment  space) 

(Terminator) 
(Terminator) 


Sample  of  the  output: 

SNAP 

A  B 

070000  000000 

000672  001005 

000241  000242 
000675  001147 
000313  000000 
001005  000000 

000242  777746 

p=  000247 


CALL  SNAP 


17456206530400403012 
17234400000000000000 
60463220160222761055 
17204000000000000000 
00000000000000000000 

17456206530400403012 
17316724175362553657 


01000235720701000000 
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As  shown,  the  snap  includes  the  current  address  and 
the  current  instruction  word. 
B.   Interpreted  dump.   A  core  dump  may  he  obtained  in  either 
octal,  integer,  floating  point,  or  BCD  (i.e.  alphanumeric) 
Provision  is  made  for  giving  an  alphanumeric  label  to 
each  dump .   The  dump  is  given  when  called,  and  may  be 
called  as  often  as  desired. 

CALL  WDUEPCKBA) 
The  parameters  are  as  follows: 
KBA(l)  =  lOH       (Any  ten  character  name) 
KBA(2)  =  LOWADD    (The  starting  address  of  the  dump) 
KBA(5)  =  HIADD     (The  last  address+1  of  the  dump) 
KBA(4)  =  P         (The  format  desired:   1  for  octal, 

2  for  integer,  5  for  floating 

point,  4  for  BCD) 
Not  more  than  five  repetitions  of  the  same  ni;Lmber  will 
be  printed,  the  rest  being  omitted  at  the  end  of  the 
line.   No  numbers  are  omitted  in  the  middle  of  a  line, 
a  line  is  always  5  words  across. 
Sample  of  the  output: 

INTERPRETED  DUMP  - 

PARAMS 

001015    0000000000000000000  5   00000000000000000001  etc. 

001022    00000000000000000000    00000000000000000000  etc. 

001152    17456025364736452336    17770000000000000000  etc. 
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INTERPRETED  DUMP  - 

MATRIX  Z 
007110    -1.62685055547E-K)7    I.98865OII619E+I2  etc. 
007115  .0E-K)0  lOE+00   etc. 

(The  octal  addresses  on  the  left  margin  give  the  starting 

address  of  each  line  and  thus  show  where  mombers  have 

been  left  out . ) 

C.  Reports .  Various  types  of  reports  are  provided: 

a  report  of  up-to  50  most  recent  branch  instructions, 

a  report  of  up-to  50  most  recent  return  Jump 

instructions,  a  report  of  up-to  I50  most  recent  stores, 

and  a  report  of  from  I5O  to  600  most-recently-executed 

instructions.   These  reports  are  given  automatically 

in  case  of  a  fatal  error,  but  they  are  also  given  when 

called  for.   All  reports  are  in  the  same  format  as  the 

OPTRACE  except  the  store  report,  which  merely  gives 

addresses  and  contents  destroyed  by  the  stores. 

CALL  REPORT(N)    (If  N  is  1,  a  store  report  will  be  given, 

if  2,  a  branch  report,  if  3^  an  RJ 
report,  if  h,    a  backup  trace  of  recent 
instructions,  if  0,  all  of  these; 
and  if  otherwise,  an  error  message 
and  no  reports) 

D.  Dump  of  selected  locations.   To  dump  the  current 
contents  of  selected  locations,  a  parameter  list 
identical  in  form  to  the  parameter  list  for  LOCTRAC 
(q.v.)  may  be  used.   In  fact,  the  same  parameter  list 
can  be  used . 
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CALL  REPORT (KBA) 

The  parameters  are: 

KBA(l)  =  5 

KBA (2)    =   XLOCP(LOCKBA) 

("LOCKBA"  Is  the  base  address  of  a  parameter  list 
identical  in  form  to  that  of  LOCTRAC . ) 

(In  case  of  fatal  error,  this  report  is  also  given 
if  it  has  ever  been  previously  called;  and  the  last 
such  parameter  list  will  be  the  one  used.) 

V.    TRAPS 

A.   Traps  on  op  codes .   The  user  may  select  any  combination 
of  op  codes  and  with  each  the  starting  address  of  a 
section  of  code  which  he  wishes  to  execute  each  time 
the  specified  op  code  is  encountered.   (This  feature 
may  be  used  to  study  the  frequency  of  occurrence  of 
the  various  op  codes  for  purposes  of  compiler  modifica- 
tion or  future  machine  design.) 
(If  the  user  wishes  to  modify  his  registers  during  a 
trap  routine,  he  must  have  selected  parameter  number  5 
in  the  call  to  WATCHIT.   He  is  free  to  use  any  registers 
he  wishes  during  his  trap  routine  without  upsetting  the 
normal  flow  or  expectations  of  his  program;  however,  if 
he  wishes  some  of  his  changes  in  the  registers  to  persist 
after  a  trap  routine,  he  must  make  these  changes  to  the 
area  of  core  where  he  has  requested  his  registers  to 
be  stored.  --The  same  is  true  of  all  the  trap  options.) 
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CALL  OPTRAP(KBA) 

The  parameter  list  is  as  follows: 

KBA(l)  =  N         (The  number  of  parameters  In  this  list) 
KBA(2)  =  OPl       (An  op  code) 

KBA(3)  =  TRAPADDl   (The  starting  address  of  the  first  execut- 
able instruction  of  a  trap  routine) 

KBA(  )  =  OPn 
KBA(N+1)=  TRAPADDn 
(Note:  The  trap  routine  must  end  with  a  call  to  CONTINU. 

All  WATCHR  facilities  continue  to  be  available  to  the 

user  during  his  trap  routine  unless  he  calls  DON¥ACH.) 

Any  number  of  traps  of  any  type  may  be  set  and  will  be 

operable  simultaneously. 

Traps  always  occur  before  the  Instruction  in  question 

is  executed. 

When  three  traps  occur  on  the  same  instruction,  the 

order  is  CONTRAP,  OPTRAP,  and  then  STORTEIP  or  LOADTRP  . 

If  TRAPADDl  is  zero,  and  if  WATCHR  is  either  in  console 

mode  or  in  SHARER  mode,  WATCHR,  instead  of  trapping, 

will  pause  and  a  message  will  appear  on  the  scopes  or, 

alternatively,  on  the  teletype.) 

Op  code  traps  may  be  unset  in  an  exactly  analogous  way 

by  calling  OPOFF  or  all  may  be  turned  off  with  OPEND. 

CALL   OPOFF (KBA) 

CALL  OPEND 
The  parameter  list  is  the  same  as  for  OPTRAP.   The 

parameter  list  does  not  reside  in  the  user's  program, 

so  the  locations  are  free  after  each  call.   (Additions 

and  deletions  are  possible.) 
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B.  Traps  on  addresses.   (Breakpoint)   When  program  control 
(the  P  register)  arrives  at  a  certain  address,  a  trap 
to  a  trap  routine  (or  a  pause)  will  result.   The  use  of 
registers  during  a  trap  routine  is  the  same  as  for 
OPTRAP  (§V.A.) 

CALL   CONTRAP(KBA) 

The  parameter  list  is  as  follows: 

KBA(l)  =  N         (The  number  of  parameters  in  this  list) 
KBA(2)  =  ADDl      (An  address) 

KBA(3)  -  TRAPADDl   (Address  of  the  first  instruction  of  a 

trap  routine) 

KBA(  )  -  ADDn 
KBA(N+1)  =  TRAPADDn 

The  list  of  addresses  may  be  added  to  by  later  calls, 

but  not  more  than  65  addresses  may  be  set  at  any  one 

time . 

A  TRAPADDl  of  0  selects  the  console  or  the  teletype. 

Deletions  may  be  made  in  an  exactly  analogous  way, 

using  CONOFF,  or  the  list  may  be  wiped  out  using  GONEND. 

CALL  CONOFF (KBA) 
CALL  CONEND 

C.  Traps  on  stores  into  specified  locations.   This  option  is 
analogous  to  CONTRAP  except  that  the  addresses  selected 
are  addresses  into  which  stores  may  be  made  or  are 
expected.   The  trap  routine  nay  be  used  as  an  extension 
of  the  diagnostic  or  Informative  capabilities  of  the 
WATCHR .   It  may  also  be  used  as  a  means  of  turning  on 
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or  off  other  WATCHR  options  to  eliminate  possible 

Irrelevant  or  excessive  output. 

(All  WATCHR  trap  settings  are  operable  simultaneously, 

but  no  traps  during  a  trap  routine  can  occur.) 

CALL  STORTRP(KBA) 

The  parameter  list  is  as  follows: 

KBA(l)  =  N 

KBA(2)  =  LOCI   (An  address  into  which  a  store  is  expected) 

KBA(5)  =  TRAPADDl 

KBA(  )  =  LOCn 
KBA(N+1)  =  TRAPADDn 

The  list  may  be  added  to  or  deleted  from,  but  no  more 

than  63  locations  are  permitted  to  be  set  at  any  one 

time . 

CALL  STOROFF(KBA) 
CALL   STOREND 

D.   Traps  on  loads  from  specified  locations.   This  option 

is  analogous  to  STORTRP  except  that  the  addresses 

chosen  are  to  be  trapped  on  when  their  contents  are 

loaded  into  the  registers. 

(A  TRAPADD  of  zero  creates  a  pause  and  a  message  on 

the  console  or  teletype.) 

CALL  LOADTRP(KBA) 

The  parameter  list  is  as  follows: 
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KBA(l)  =  N         (The  number  of  parameters  on  this  list) 
KBA(2)  =  LOCI      (An  address  from  which  a  load  Is  expected) 
KBA(3)  =  TRAPADDl   (The  first  address  of  a  trap  routine) 

KBA(  )  =  LOCn 
KBA(N+1)  =  TRAPADDn 

The  list  may  be  added  to  or  subtracted  from.   It  does 

not  reside  in  the  user's  program  area,  however,  so 

those  locations  used  to  set  up  these  parameters  are 

free  for  other  uses. 

CALL  LOADOPP(KBA) 
CALL  LOADEND 

These  calls  delete  addresses  from  the  list  or, 

respectively,  erase  the  list  completely.   The  addresses 

may  be  selected  in  any  order  whatever. 

Continuing  after  a  trap .   To  continue  processing  after 

a  trap  routine,  the  user  must  execute  a  call  to  CONTINU, 

if  he  wishes  to  regain  WATCHR  control.  After  such  a  call, 

the  program  will  continue  at  the  same  point  as  though  no 

break  had  occurred.   If  the  user  wishes,  he  may  call 

DONWACH  and  execute  his  trap  routine  outside  WATCHR  control. 

In  this  case,  a  call  to  WATCHIT  is  not  necessary,  and  a 

call  to  CONTINU  will  effectively  regain  control. 

CALL  CONTINU (K)   (K  is  an  address  which  contains  a 

zero  normally,  but  which  will,  if 
non-zero,  be  taken  to  contain  an 
address  at  which  it  is  desired  to 
continue  processing  (if  a  deliberate 
break  in  the  continuity  is  desired)) 


Example;   SBl  BO 

RJ    CONTINU 
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VI .   CHARTR 

To  produce  an  organization  chart  of  the  user's  program, 
a  call  to  CHARTR  should  be  executed  near  the  beginning 
of  the  program  and  control  should  not  leave  WATCHR  until 
the  end.   The  program  must  end  with  a  call  to  D0N¥ACH(1), 
and  parts  of  the  program  not  executed  In  this  run  will 
not  be  represented. 

The  subroutines  In  the  user's  program  will  be  numbered 
and  their  addresses  printed  out,  together  with  a  list 
of  all  the  other  subroutines  which  call  each  of  them 
and  a  list  of  all  the  other  subroutines  which  each  of 
them  calls . 

If  the  SUBTFIAC  option  is  also  on,  the  comments  given  in 
the  SUBTRAC  parameter  list  will  also  be  included. 

CALL  CHARTR 

Sample  of  the  output: 

0 .  000000 

CALLS  CALLED  BY 

1.  AAB      (001140) 

2.  ABA      (002422) 

1.  001140   AAB   ADJUST  PROGRAM  FIELD  LENGTH 

CALLS  CALLED  BY 

3.  QED     (01510)  (000000) 
SUBROUTINE  TO  PROVE  THEOREMS 

6.   LST      (025110) 

SUBROUTINE  TO  PROCESS  FORMAT  STATEMENTS 

2.  002422   ABA 

Address  000000  designates  the  main  program.   In  this 

example  no  comments  were  provided  In  the  parameter  list 

of  SUBTRAC  for  ABA. 
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VII.  SHARER  MODE 

When  the  user's  program  Is  being  run  under  WATCHR 

control  from  a  teletype,  using  the  SHARER  system, 

or  any  other  such  time-sharing  system  which  is  capable 

of  inputting  display-code  messages,  a  number  of  questions 

will  be  answered  or  requests  carried  out  which  originate 

from  the  teletype. 

These  requests  may  be  issued  whenever  the  program  comes 

to  a  pause  (on  account  of  a  trap,  or  because  of  being 

in  step  mode,  or  by  force  stop).   Requests  will  be 

accepted  until  the  word  "GO"  is  typed. 

The  requests  and  questions  which  will  be  accepted  are 

as  follows: 

A.  GO  BACK  N  STEPS 

Here,  the  "N"  represents  some  number  less  than  or  equal 
to  600.   The  WATCHR  will  notify  the  user  when  the 
request  has  been  completed. 

B .  CALL  XXXX 

"XXKX"  is  the  name  of  a  WATCHR  option  and  that  option 
will  be  executed  when  this  command  is  typed. 
(The  BA  must  previously  have  been  set  into  Bl  and  the 
parameters  set  into  core  locations  at  BA  and  following.) 

C.  SET  YY      TO   ZZZZZZZZZ 

YY  may  be  a  register,  such  as  "A5",  "XO",  or  an  octal 
core  address.   ZZZZZZZZZ  represents  the  desired  contents 

of  yy. 
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D.  IS   YY   R   ZZZZZZZZZZZ? 

YY  again  is  either  a  register  or  a  core  location, 

however.  If  ZZZZZZZZZZZ  Is  a  slx-dlglt  octal  n\Ainber 

It  will  be  taken  to  be  an  address  and  Its  contents 

compared  with  the  contents  of  YY  (iff  YY  is  an 

address  and  not  a  register) .   If  YY  Is  a  register, 

ZZZZZZZZZZZ  will  be  taken  to  be  the  possible  contents 

of  that  register. 

"R"  is  a  symbol  for  "equal  to",  "less  than",  or 

"greater  than." 

WATCHR  will  respond  to  this  question  with  a  "YES"  or 

"NO". 

E.  WHAT  IS  IN  LOCATION  NNNNNN  ? 

WATCHR  will  respond  with  the  contents,  in  octal, 
of  location  NNNNNN. 

P.       LOCATE  SUBROUTINE  SSSSSSS 

WATCHR  returns  the  first  address  of  the  subroutine 
whose  alphanumeric  name  is  SSSSSSS,  if  it  exists. 

G.        LOCATE  THE  WORD  WHICH  CONTAINS   00000000000000000000 
The  first  such  address  will  be  returned,  if  it  exists. 

H.        WHICH  SUBROUTINE  CONTAINS  ADERESS   AAAAAA  ? 

WATCHR  returns  the  alphanumeric  name  of  the  subroutine 

if  it  can  be  found.   A  reply  will  be  given  in  either  case. 

I.       ONSTEP 

WATCHR  will  set  a  switch  to  start  processing  in  step 
mode  (i.e.  one  instruction  at  a  time,  pausing  after 
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each  Instruction)  and  will  be  In  step  mode  when  GO 

is  typed. 
J.        OPFSTEP 

Similarly J  to  unset  the  stepmode  switch. 
K.       ONCYCLE 

WATCHR  will  set  a  switch  to  process  In  steps  of  300,^^ 

instructions  at  a  time  before  pausing. 
L.       OPFCYCLE 

Similarly,  to  unset  the  cycle  mode  switch. 
M.        FORCE  STOP 

(The  user's  program  will  halt  after  next 

instruction.) 
N.       START  PROCESSING  AT   AAAAAA 

WATCHR  will  prepare  to  begin  at  address  AAAAAA 

when  GO  is  typed. 
0.       GO 

WATCHR  will  resume  processing  until  another  pause 

condition  is  detected  or  encountered. 
(Note:   None  of  the  above  commands  requires  specific 

fonnats  or  periods  at  the  end.   Any  reasonable 

approximation  to  the  command  as  written  here  will 

suffice . ) 

It  is  anticipated  that  the  SHARER  time-sharing  system 

will  have  the  capability  of  placing  a  program  under 

WATCHR  control  initially,  so  that  thereafter,  the  user 
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may  control  has  program  and  communicate  with  MATCHR 

whenever  a  pause  condition  obtains.) 

If  a  command  Is  unrecognizable.  It  will  be  so  Indicated 

on  the  teletype  and  may  be  re-Issued.   No  damage  will 

result. 
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APPENDIX  A 
The  Use  and  Cost  of  WATCHR 

1.    Suggestion  for  the  use  of  WATCHR. 

a.  Compile  and  assemble  your  program  to  remove  FORTRAN 
errors . 

b .  Run  the  program  alone  getting  frequent  prlnt-outs  of 
the  values  of  key  variables,  correct  and  Incorrect. 

c.  Feed  the  Information,  thus  obtained.  Into  CHECKR 

and  RECOVR  and  Insert  calls  to  COMPARE  at  appropriate 
places.   This  will  guarantee  a  legitimate  test  of  all 
sections  and  subroutines  of  your  program.   If  the 
logical  flow  Is  In  the  least  complex,  MAP  should  be 
turned  on  for  the  duration  of  the  run.   (You  should 
have  removed  most  of  your  own  printouts  for  this  run, 
compensating.  If  need  be,  by  a  call  to  LOCTRACE.) 

d.  Make  any  changes  and  correct  the  errors  uncovered 
and  run  alone  again  (with  your  own  printouts). 

e.  Run  again  under  WATCHR,  going  under  WATCHR  control 
only  when  approaching  troublesome  sections  of  your 
program.   Here,  a  more  thorough  use  of  CHECKR  and 
LOCTRACE  may  be  made,  based  on  the  Information  obtained 
from  previous  runs . 

This  should  be  sufficient,  whatever  the  length  of  the 
program  for  all  but  the  most  obscure  errors.   For  such 
sections,  the  above  options  may  be  augmented  by  the 
OPTRACE,  REPTRAC,     STORCHK,  or  trap  options. 
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(Remember,  all  WATCHR  options  are  available 
simultaneously  and  may  be  turned  on  or  off  or 
modified  at  will.) 

2.    The  Cost  of  WATCHR. 

a.  Running  speed.   The  user's  program,  at  those  times 
when  it  is  running  under  WATCHR  control  will  run  from 

40  to  300  times  slower,  depending  on  the  options  in  use. 

b.  Total  computer  time  used. 

1)  The  number  of  test  runs  required  in  the  preparation 
of  a  program  should,  with  a  judicious  use  of  WATCHR, 
be  about  5  times  less. 

2)  Programs  frequently  generate  errcr  s  early  in  a  run 
which  (a)  cause  endless  loops,  or  (b)  produce  "garbage" 
throughout  core,  or  (c)  so  alter  the  program  or  the 
data  that  the  rest  of  the  run  (which  may  be  a  long 
one)  is  meaningless.   Under  WATCHR 's  STORCHK  and 
COMPARE  options,  this  cannot  occur.   At  the  worst, 
WATCHR  will  terminate  the  run  as  soon  as  the  run 
becomes  invalid,  and  thus  will  not  waste  tjone  on  a 
potentially  long  run. 

5)  Thus,  total  computer  time  should,  with  a  Judicious 
use  of  WATCHR,  be  less  than  or  equal  to  the  total 
computer  time  used  without  WATCHR. 

(N.B.  "judicious  use":  obviously,  a  use  of  WATCHR 
which  consists  of  simply  tracing  every  instruction 
is  not  what  is  meant  here.) 
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c.  Total  program-preparation  time.  In  weeks  and  months, 
should  be  shortened  by  a  factor  of  5  to  10  by  a 
judicious  use  of  WATCHR , 

d.  The  total  number  of  lines  of  output  should  not  be 
greater  than  1  page  per  3  pages  of  erroneous  Ascent 
code . 

e.  Space:   25o  k  of  central  memory. 

Note:   the  relative  cost  of  the  various  options 
in  terms  of  running  speed  is  given  by  the  following 
list,  arranged  in  order,  slowest  to  fastest,  as  one 
goes   from  top  to  bottom  and  from  left  to  right: 

(a)  OPTRACE,  REGTRAC,   CONTRAP 

(b)  CHECKR,  LOOPCHK,  STORCHK,  LOADCHK,  LOCTRAC,  REPTRAC 

(c)  STORTRP,   LOADIRP,   SUBTRAC,   CHARTR 

(d)  REPORT,   DUMP,   COMPARE 

(e)  OPIRAP,   MAP,  SNAP 
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INDEX 


Addresses,  trap  on,  CONTRAP 

Answers,  validity  check  of,  CHECKR 

Breakpoint (See  §VI) 

Examine  core  locations   COMPARE 

Examine  the  contents  of  registers  COMPARE 

Fatal  errors (See  §11. A,  and  RECOVR) 

Initialization (See  §1) 

Instructions,  trace  of  all,    OPTRACE 

trap  of  any,   OPTRAP 

Interrupts (See  §V) 

Logical  flow,  trace  of,  MAP 

On-Llne  debugging  (See  §VII) 

Organization  chart  of  user's  program   CHARTR 

Path  of  program,  trace  of,   MAP 

Pausing  SHARER  mode,  OPTRAP, 

CONTOAP,  STORIRP,  LOADTRP 

Registers,  trace  of  changes  to,  REGTRAC 

Subroutine  calls,  trace  of,  SUBTRAC 

Validity  checks (See  §11) 

Variables,  trace  of  changes  to,  LOCTRAC 

traps  on  changes  to, STORTRP 

Variables,  trace  of  references  to,   REPTRAC 

trap  on  references  to, LOADTRP 


43 


This  report  was  prepared  as  an  account  of 
Government  sponsored  work.   Neither  the 
United  States,  nor  the  Commission,  nor  any 
person  acting  on  behalf  of  the  Commission: 

A.  Makes  any  warranty  or  representation, 
express  or  implied,  with  respect  to  the 
accuracy,  completeness,  or  usefulness  of 
the  Information  contained  In  this  report, 
or  that  the  use  of  any  information, 
apparatus,  method,  or  process  disclosed 
In  this  report  may  not  infringe  privately 
owned  rights;  or 

B.  Assumes  any  liabilities  with  respect  to 
the  use  of,  or  for  damages  resulting  from 
the  use  of  any  information,  apparatus, 
method,  or  process  disclosed  In  this 
report . 

As  used  in  the  above,  "person  acting  on  behalf 
of  the  Commission"  Includes  any  employee  or 
contractor  of  the  Commission,  or  employee  of 
such  contractor,  to  the  extent  that  such  em- 
ployee or  contractor  of  the  Commission,  or 
employee  of  such  contractor  prepares,  dis- 
seminates, or  provides  access  to,  any  infor- 
mation pursuant  to  his  employment  or  contract 
with  the  Commission,  or  his  employment  with 
such  contractor. 


hh 


5f  P  2  1  1966 

DATE  DUE                 "° 

ilARl'!    6ir 

GAYLORD 

PRINTED  IN  U    S    A. 

RYU 
NYO- 

A'Y')- 


c.l 


c.l 

c.l 


u.  L  u 

INYO- 

l[).80-58     Draughon 

AUTHOR  W  A  'IT  Up T    i     r = 

/vaxu.^^t  ixi,    a  ppo- 
=__^___liser '  s  manual . 


,V'AP  i.<^ 


■5~otrtft79^j'2_ 


N.Y.U.  Courant  Institute  of 
Mathematical  Sciences 

251  Mercer  St. 
New  York  12,  N.  Y. 


